home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 49 / Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso / -serious- / misc / mmulib / contributions / sashimi / sashimi.doc < prev    next >
Text File  |  1999-11-29  |  9KB  |  247 lines
  1. Sashimi v1.6
  2.  
  3. Written by Olaf `Olsen' Barthel <olsen@sourcery.han.de>
  4. Public Domain
  5.  
  6.  
  7. Sashimi intercepts raw serial debugging output on your own machine; command
  8. line options are:
  9.  
  10. Startup: [RECOVER=name]
  11.          [ON] [BUFK=n (n must be a power of 2)] [BUFFERSIZE=n] [NOPROMPT]
  12.          [QUIET] [ASKEXIT] [ASKSAVE] [TIMERON] [CONSOLE] [WINDOW=name]
  13.  
  14. Runtime: [OFF] [SAVE] [SAVEAS=name] [EMPTY]
  15.  
  16.  
  17. Sashimi is a tool to intercept the raw serial output of Enforcer, Mungwall,
  18. and all tool and application debugging output that uses kprintf(). This
  19. makes it possible to use serial debugging on a single Amiga, without
  20. interfering with attached serial hardware such as modems and serial
  21. printers.
  22.  
  23. This is a drop-in replacement for the "Sushi" tool, as written by Carolyn
  24. Scheppner. Well, not exactly. Sashimi has a few different/new features and
  25. does not support the complete feature set of the "Sushi" tool. Sashimi only
  26. runs from Shell and requires Kickstart 2.04 or higher. Sashimi cannot patch
  27. the older Enforcer at run time which means that you have to use Enforcer
  28. V37 or an equivalent like CyberGuard.
  29.  
  30.  
  31. Quick usage
  32. ===========
  33. Here's what's in my "S:User-Startup" file:
  34.  
  35. Run >NIL: MungWall NAMETAG
  36. Run >NIL: Enforcer RAWIO
  37. Run >NIL: Sashimi CONSOLE BUFK=64 NOPROMPT ASKEXIT ASKSAVE
  38.  
  39. All standard serial debugging functions are intercepted. Currently, the
  40. patch to the serial debugging input function just returns a `y'. Standard
  41. serial debugging output and Enforcer output go into Sashimi's circular buffer
  42. (the size is user-definable, with a default size of 32K), where it is
  43. noticed by the Sashimi process and written to the output window. The
  44. Sashimi process is signalled whenever a carriage return or linefeed comes
  45. through kprintf().
  46.  
  47. Sashimi has several startup options, and several runtime options:
  48.  
  49. Startup: [RECOVER=name]
  50.          [ON] [BUFK=n (n must be a power of 2)] [BUFFERSIZE=n] [NOPROMPT]
  51.          [QUIET] [ASKEXIT] [ASKSAVE] [TIMERON] [CONSOLE] [WINDOW=name]
  52.  
  53. Runtime: [OFF] [SAVE] [SAVEAS=name] [EMPTY]
  54.  
  55.  
  56. Startup options
  57. ===============
  58. RECOVER=name    Sashimi will search the Amiga memory for the buffer created
  59.                 and maintained by a previous invocation of Sashimi. This is
  60.                 useful if the system crashed before you had any chance to
  61.                 save the Sashimi buffer to disk. While the search is in
  62.                 progress the system will be frozen. There is no guarantee
  63.                 that Sashimi will find any older buffer or that the contents
  64.                 of the buffer found will still be intact. Once the data is
  65.                 found, it will be saved to the file with the given name.
  66.  
  67.                 Sashimi will exit immediately after processing the recovery
  68.                 command. No further action will be taken. Depending on whether
  69.                 it was successful in recovering the data, Sashimi's return
  70.                 code will be either 0 (= success) or 5 (= failure).
  71.  
  72. ON              Default (not required)
  73.  
  74. BUFK=n          Changes the circular buffer size from default 32K to specified
  75.                 power-of-2 K from 4K to whatever you like, i.e. BUFK=8 will
  76.                 allocate a buffer of 8192 bytes.
  77.  
  78. BUFFERSIZE=n    Changes the circular buffer size from default 32K to specified
  79.                 buffer size, i.e. BUFFERSIZE=8000 will allocate a buffer
  80.                 of 8000 bytes.
  81.  
  82. NOPROMPT        Turns off the "Sashimi installed" prompt. This is useful if
  83.                 the Sashimi output is redirected to an AUTO CON window such
  84.                 as in conjunction with the CONSOLE option.
  85.  
  86. QUIET           Causes Sashimi to just buffer all debugging output.
  87.                 This effectively silences serial debugging output.
  88.  
  89. ASKSAVE         Cause Sashimi to ask you if you want to save the buffer
  90.                 when you exit Sashimi.  If there's nothing in the buffer,
  91.                 it won't ask.
  92.  
  93. ASKEXIT         Cause Sashimi to ask you if you *really* want to exit if
  94.                 a [Ctrl]+C signal is received.  This is good for people like
  95.                 me who might accidentally [Ctrl]+C in a Sashimi window when
  96.                 they meant to do it somewhere else. This option should
  97.                 only be used if Sashimi has an input stream - i.e. if Sashimi
  98.                 is not run/redirected, or if Sashimi has in/out redirection
  99.                 in a CONSOLE window.
  100.  
  101. TIMERON         Cause Sashimi to wake up every 1/10 second to check for
  102.                 output. Without this option, Sashimi will just wake up every
  103.                 time a carriage return or linefeed is output.
  104.  
  105. CONSOLE         This will make Sashimi open a console output window for itself
  106.                 which all input and output will go into. Unless you provide a
  107.                 console window specifier (see WINDOW option), Sashimi will use:
  108.  
  109.                 CON:0/20/640/100/Sashimi  [Ctrl]+E=Empty  [Ctrl]+F=File  [Ctrl]+D=Reset console/AUTO/CLOSE/WAIT/INACTIVE
  110.  
  111. WINDOW=name     This option works in conjunction with the CONSOLE option and
  112.                 allows you to override the default console window specifier.
  113.  
  114.  
  115. Runtime options
  116. ===============
  117. OFF             Signals the active running copy of Sashimi to exit.
  118.  
  119. EMPTY           Finds the active running copy of Sashimi and empties its
  120.                 buffer.
  121.  
  122. SAVE            Finds the active running copy of Sashimi and saves its buffer
  123.                 as "T:sashimi.out".
  124.  
  125. SAVEAS=name     Finds the active running copy of Sashimi and saves its buffer
  126.                 as the specified file name.
  127.  
  128.  
  129. Example startup usage
  130. =====================
  131.  
  132. Sashimi ASKSAVE (in its own shell window)
  133.  
  134. Run >NIL: Sashimi >"CON:0/20/640/120/Sashimi/AUTO/CLOSE/WAIT/INACTIVE" ON NOPROMPT
  135.  
  136. Run Sashimi >ram:hits (all output redirected to a file)
  137.  
  138.  
  139. Keyboard and Break signals
  140. ==========================
  141. [Ctrl]+C: To quit Sashimi, [Ctrl]+C it (if it has its own window), send it
  142.           a [Ctrl]+C signal with the Break command, or run Sashimi a second
  143.           time with the OFF keyword.
  144.  
  145. [Ctrl]+D: This sends a control sequence to the output console to reset it.
  146.           Very handy in case garbage data has changed the character set
  147.           or the text rendering colours.
  148.  
  149. [Ctrl]+E: Tells Sashimi to empty (clear) its buffer.
  150.  
  151. [Ctrl]+F: Tells Sashimi to save its own buffer to the file "T:sashimi.out"
  152.  
  153.  
  154. Other runtime usage
  155. ===================
  156. Sashimi OFF                     ; tell active running Sashimi to try to exit
  157. Sashimi SAVE                    ; save buffer of active Sashimi
  158. Sashimi SAVEAS ram:myhits EMPTY ; save buffer as ram:myhits and clear buffer
  159.  
  160. Usually, I just hit [Ctrl]+F in the Sashimi window, and it saves its buffer
  161. as "T:sashimi.out".
  162.  
  163.  
  164. Programmer interface
  165. ====================
  166. Sorry, no programmer interface. "Sushi" had one, but I did not see much
  167. sense in replicating this functionality.
  168.  
  169.  
  170. Why "Sashimi"?
  171. ==============
  172. I got bitten by bugs in "Sushi", and not just once. Whenever the Sushi
  173. circular buffer would wrap around, there was a good chance part of the buffer
  174. would still be filled with random data when getting saved to disk. If a large
  175. amount of data would be sent through the kprintf() interface, Sushi would
  176. occasionally "hickup" and regurgitate stale data from its buffer. I took
  177. this as indications that the Sushi buffer management code was none too
  178. robust. Another thing that struck me as odd was the fact that sometimes
  179. Sushi would stop reporting incoming kprintf() output and effectively behave
  180. as if it had been stopped with [Ctrl]+C. Sushi also had a tendency to block
  181. screen output when printing its buffer; it would output the buffer in a
  182. single Write() operation, causing the console window to lock the display.
  183. And while that operation was in progress, you could not suspend window output
  184. or stop it.
  185.  
  186. Sashimi tries to do better in these situations. The algorithms for
  187. maintaining the circular buffer (or FIFO) are different. And just in case
  188. there is a bug in the code, I have provided the complete tool source code.
  189.  
  190.  
  191. Author
  192. ======
  193. Sashimi was written by Olaf `Olsen' Barthel, with "Sushi" by Carolyn
  194. Scheppner as a reference. Sushi was in turn influenced by the "Reporter"
  195. and "Detective" tools written by Steve Tibbett and Christian E. Hopps.
  196.  
  197. My postal address:
  198.  
  199.    Olaf Barthel
  200.    Brabeckstrasse 35
  201.    D-30559 Hannover
  202.    Federal Republic of Germany
  203.  
  204. My e-mail address:
  205.  
  206.    olsen@sourcery.han.de
  207.  
  208.  
  209. History
  210. =======
  211.  
  212. Sashimi 1.6 (20.6.99)
  213.  
  214.     - Sashimi could cause the entire system to hang due to an
  215.       unmatched Disable() in the RawPutChar wedge [David Gerber].
  216.  
  217.     - If Sashimi is not already running "Sashimi OFF" will no
  218.       longer restart it.
  219.  
  220. Sashimi 1.5 (8.2.99)
  221.  
  222.     - Made the FIFO access routines into atomic operations. This
  223.       reduces the risk of two programs trying to modify the
  224.       FIFO bookkeeping variables at the same time.
  225.  
  226.     - Fixed a bug in the FIFO management code which would cause
  227.       Sashimi to regurgitate stale data after a buffer overrun.
  228.       Strangely, this was one of the bugs in Sushi I wanted to
  229.       avoid...
  230.  
  231.     - Added the new RECOVER functionality.
  232.  
  233. Sashimi 1.4 (11.9.98)
  234.  
  235.     - The Sashimi RawPutChar() patch now saves and restores
  236.       the contents of A0 and A1. This is necessary since
  237.       the KPutStr() code relies upon A0 to remain unchanged
  238.       after each call to RawPutChar() [Stuart Kyzer Caie].
  239.  
  240. Sashimi 1.3 (07.04.98)
  241.  
  242.     - Updated the console window title text
  243.  
  244. Sashimi 1.2 (05.04.98)
  245.  
  246.     - Added the [Ctrl]+D console reset command.
  247.